about these scripts

Documentation and information about the latest version of these scripts can be found here and downloaded here.

These scripts were written to extend Tactical Battle's functionality. The scripts primary focus for now is on allowing you to do more with effects. To use these scripts, extract the .zip archive to the data for tb folder. In your map pack's Map Pack Settings.txt file, add the following:

load_scripts victorious

or if you are already using other scripts, append victorious to the end of that line.

a warning about infinite recursion

These scripts are very powerful and if not used properly will cause tactical battle to go into an infinite loop and crash. For example, you have effects_on_apply Y set on effect x, and effects_on_apply x on effect y. Being affected by x causes y to be applied and vice versa, creating an infinite cycle. Though this is a trivial mistake that most people would intuitively avoid making, it may happen in more complex cases such as using replace_effects, effects_on_apply and effects_on_remove together.

Preliminary notes

Effect Flags

Optional Duration Modifiers

Most of these scripts will require you to specify effects that will be applied to a target. It is usually done by a comma seperated list of effects such as: poison, plague. In addition to specifying the effect that you want applied, you may also append optional modifiers to the effect to change its duration using the following format: EffectName[modifier]. The modifier, if specified, must be enclosed in square brackets []. The following modifiers are supported:

This allows having different durations for the same effect depending on where the effect is used, without creating duplicates of the same effect with different durations.

Examples: If the magma tile effect has a duration of 5,

effects_on_entry, remove_effects_on_entry

Argument: string, where string is a single effect or a list of unit effects, each separated by a comma followed by a space. Optional duration modifiers can be used with effects_on_entry

Useable on: tile effects

Applies or removes a list of unit effects to all units entering the tile affected by the scripted tile effect. Not_affects_flying on tile effects is respected for these flags. Because there is currently no actual before or after movement event for scripters to use, this only works if the target uses an item or skill to move onto the tile. It will not work if the target was moved onto the tile by a script. This is also the reason why there aren't corresponding flags for leaving the tile.

Examples:

effects_on_apply, effects_on_fizzle and effects_on_remove

Argument: string, where string is a single effect or a list of effects, each separated by a comma followed by a space. Optional duration modifiers can be used with all 3 flags.

Useable on: both tile and unit effects for effects_on_apply and effects_on_remove. Only unit effects for effects_on_fizzle.

Applies a list of additional effects upon the application, fizzling or removal of the scripted effect. This can be particularly useful if you want multiple effects to happen when a point reaches zero (because the game only allows you to specify a single one). Effects_on_fizzle can only be used on unit effects at this time because the effect fizzling event currently does not fire on tile effects. Effect application is performed in the following way:

Examples:

map_preload_effects

Argument: string, where string contains tile-effect associations separated by a semicolon, followed by a space. A tile-effect association has the following format: x, y = effect_1, effect_2, effect_n. X and Y are 1-based coordinates of tiles - for example, 1,1 is the top left corner of the map. Optional duration modifiers may be used in the effects list.

Useable on: maps

Applies a list of effects on tiles and units for some coordinates upon map load. This can be useful if you need effects with extra scripted functionality that can't be achieved with terrain.

The coordinates these scripts use correspond to those displayed with the "y-coordinates decrease as you move up" setting turned off in TB options. These effects will not be reapplied if a saved game is reloaded. This script works when the map is opened in the map editor, which is useful for ensuring that effects are being applied on the right tiles.

Examples:

remove_effects_on_apply, remove_effects_on_fizzle, remove_effects_on_remove

Argument: string, where string is a single effect or a list of effects, each separated by a comma followed by a space.

Useable on: both tile and unit effects for remove_effects_on_apply and remove_effects_on_remove. Only unit effects for remove_effects_on_fizzle.

Removes a list of effects upon the application, fizzling or removal of the scripted effect. Remove_effects_on_fizzle only supports unit effects at this time because the effect fizzling event currently does not fire on tile effects. Effect removal is performed in the following way:

Example:

replace_effect

Argument: string, where the string consists of effect pairs which must be either both unit or both tile effects. Effect pairs must have the format old effect|new effect. Effect pairs are separated by a comma followed by a space. Optional duration modifiers may be used with the new effect.

Supporting flags: replace_effects_limit (string), where string represents an integer, dice roll or range. This limits the number of successful effect replacements. This flag is optional.

Related flags: replace_occupants_effects

Useable on: tile and unit effects, items, skills

Performs effect replacement, similar to how replace_terrain works. The script applies replacements in the following way:

In addition, the none keyword may be usedd in the following way:

Examples:

replace_occupants_effects

Argument: string, where string consists of effect pairs which must be both unit effects. Effect pairs must have the format old effect|new effect. Effect pairs are separated by a comma followed by a space. The new effect in the replacement pair may have optional duration modifiers.

Supporting flags: replace_occupants_effects_limit (string), where string represents an integer, dice roll or range. This limits the number of successful effect replacements per tile occupant, not the number of occupants on the tile that replacements are made for. This flag is optional.

Related flags: replace_effects

Useable on: tile effects, items and skills with tile targets

This is a version of replace_effects which searches all occupants of the target tile for unit effects which can be replaced by other unit effects. Effect replacements are done for all occupants of the tile, subject to the replace_occupants_effects_limit. All other features such as the use of the none keyword are supported, so refer to the replace_effects section for detailed documentation.

effects_on_failure, self_effects_on_failure, self_tile_effects_on_failure

Argument: string, where string is a single effect or a list of effects, each separated by a comma followed by a space. Optional duration modifiers are supported for all 3 flags.

Useable on: items, skills

Apply/remove a list of effects on item use failure or skill failure.

Examples:

source_effects_on_apply, source_tile_effects_on_apply, source_effects_on_remove, source_tile_effects_on_remove, remove_source_effects_on_apply, remove_source_tile_effects_on_apply, remove_source_effects_on_remove and remove_source_tile_effects_on_remove (experimental)

Argument: string, where string is a single effect or a list of effects, each separated by a comma followed by a space. Duration modifiers are supported for source_effects_on_apply, source_tile_effects_on_apply, source_effects_on_remove and source_tile_effects_on_remove

Useable on: tile and unit effects

Apply/remove a list of additional effects to the source unit/structure of the scripted effect or the source tile upon application/removal of the scripted effect. Flags with just source as its prefix (e.g source_effects_on_apply, source_effects_on_remove) applies unit effects only to the source, while their source_tile counterparts (source_tile_effects_on_apply, source_tile_effects_on_remove) applies tile effects to the source tile and unit effects to all occupants of the source tile. The other flags work in a similar way. This feature is marked experimental because I cannot garentee being able to determine the source unit, which happens if the effect was applied through scripting. In that case, the most recent unit that used an item or performed a skill is the next best guess used. If the source still cannot be determined, it fails silently. The flags may look very long but should be quite easy to remember; for example, remove_source_tile_effects_on_remove means on the removal of the scripted effect, remove effects from the source tile.

Examples:

changelog

Feedback

Suggestions are welcome. I may be contacted on the Ian Reed's games mailing list.